This is the specification for language version 1 of SKON.
SKON, short for Space Kraken Object Notation is a data serialization language designed to be easy to understand and write. It works well for everything where JSON is normally used to and where XML is normally misused.
SKON aims to be minimal in it's functionality but very versatile in usage. It's focus should be narrow; creating a concise and easy data storage language that does not contain any bloat.
This section contains definitions for a few words that will be used in the document.
-
could is used when a parser could optionally support the directions, but in a general sense should be considered not supported.
-
should is used when there could be reasons for a parser to not follow the specification, should is a strong recommendation and should be assumed to be supported in a general sense. If a parser does not follow these directives it should advertise this clearly!
-
needs is used when the parser is required to follow the directives to conform to the SKON specification.
SKON is written in UTF-8 and that is the only encoding a parser needs to support. A parser could support other encodings but should not be expected to.
This section is only important for people interested in making a parser for SKON.
SKON is designed as a context free language. This means that it's possible to parse SKON effectivly using an LL(1) parser.
The official grammar is defined as a ANTLR4 combined grammar, though an ALL(*) parser as ANTLR4 uses is not necessary to parse SKON, any LL(1) parser should work.
The official grammar can be found here.
SKON is paired with it's own schema language SKEMA which can be read more about here.
A parser should support SKEMA validation.
In SKON there are eight data types, five "Simple" data types and two "Complex" data types.
The following is a list of all of the different data types and the some notes regarding them.
-
The length of a string should not be limited.
-
Integer values should be signed 64-bit.
-
Float values should be IEEE 754 double-precision floating-point.
-
DateTimes should be able to represent any date or time supported by the DateTime syntax.
DateTimes that only specify time of day should assume "today" as the date.
-
The number of elements in an array should not be limited in any way, though it is recommended to keep that number reasonable in respects to memory usage, file size and parsing times.
Arrays should also not be limited to just one data type. If limiting the data in an array is needed, it is recommended to validate the SKON with a SKEMA definition, as SKEMA allows for limiting of data types in an array.
-
Like with arrays the number of key-value pairs should not be limited in any way, but when writing SKON it is recommended to keep the number of elements reasonable.
If there are multiple key-value pairs with the same key the earlier values are overwritten.
Every value in SKON should end with a comma, even if it is the last element in an array or a map. This is to keep the grammar context-free. This will be reflected in the syntax examples below.
Every SKON file should be considered an implicit map without the surrounding { }.
SKON supports two types of comments. Single line comments using // and multi line comments using /* comment */ syntax.
Single line // comments end at a newline, while multi-line /* ... */ comments end at the first */. Nested comments are therefore not supported.
// Single line comment/* Multi-line comment on one line */
Multi-line example.
/*
Actual
multi-line
comment.
*/
Metadata in SKON provide the parser and user with various information about the document.
All metadata needs to be at the top of a SKON file.
Metadata entries are surrounded by ~ chracters on both sides and contain a key-value pair.
There are two metadata directives a parser needs to support. These are as follows:
Versionwhich is followed by an integer. This is the SKON language version.DocumentVersionwhich is followed by a string. This is used in applictaion to filter versions of a file.
A Version and DocumentVersion metadata directive is required at the top of every file.
If the parser supports SKEMA it should support the SKEMA directive which is followed by a string that locates the SKEMA file.
A parser could support custom metadata, but to keep compatability it should not force these to be present.
This is an example of a valid metadata header for a SKON file.
~Version: 1~
~DocumentVersion: "1.1"~
~SKEMA: "./DocumentSKEMA.skema"~
// SKON data...String values are double quoted. Unicode characters and other control characters can be escaped with a \.
The escapable control characters are:
b- Backspacen- New linef- Form feedr- Carrige returnt- Tab"- Double quote\- Backslash
"This is a normal string","This is an escaped string \n \"Quote inside of string\"",
As SKON is written in UTF-8 there is no need for special escaping of unicode characters, they are just written as any other character.
"This is unicode in a string ♥"
Integers are written as a normal integer number with no spaces
1234,10,-2147483648,
But they can also be represented in Hexadecimal using the prefix 0x.
0xFFFF,0xA,0x7FFFFFFF,
Float values can be written as two integers separated by a dot.
0.12,0.00000000001,1000.10001,
They can also we written using scientific notation using either an upper case or lower case Ee
314E-2,1.234e100,0.1E1,
Booleans in SKON are written as either true or false in only lower case.
true,false,
TRUE,False,
There are numerous ways to write date and time in SKON, all of which are based upon RFC 3339/ISO 8601.
The DateTime formats should be able to represent any date supported by the syntax.
A DateTime can be represented using the following format yyyy-MM-dd where yyyy is the year, MM is the month and dd is the day. Written as integers.
2016-10-09,1136-11-15,
DateTimes can also be represented as a time of day using the following syntax, HH:mm:ss or HH:mm:ss.sfrac followed by a UTC time zone offset written as either Z for no offset or +/-HH:mm for the appropriate UTC offset.
In this format HH is hours, mm is minutes and ss is seconds.
Additionally sfrac is a fraction of a second expressed with any precision.
A parser should be able to parse any number of sfrac digits, though it is only expected to have 3 digit sfrac (milisecond) precision but a parser could have greater precision.
12:00:00Z,16:30:20.345-03:30,12:34:56.789Z,00:00:00.000+10:15,
Date and Time can be written together written as any date and any time separated with a T.
2310-12-01T13:37:01.002+09:00,2310-12-01T13:37:01.02Z,2310-12-01T13:37:01Z,
Arrays are written as a list of values all followed by a comma surrounded by two [ ] brackets.
[ "String", "array", ],[ 123, 456, ],[ "Mixed", 1.23, "Array", true, ],
Maps are a written as a collection of key-value pairs, all followed by a comma and surrounded by two { } braces.
Keys are written as any characters exluding {, }, [, ], ", . and , ending in a :. So UTF-8 character are valid keys.
Keys must have a length of atleast one character.
Key:This_Is_A_Key:_AnotherKey:♥:
1234:::./spec/SKON v1 Spec.md:S p a c e s:
The values can be any data type and are written after the : of the key.
{
KeyToString: "String value",
KeyToInt: 1,
KeyToFloat: 1.2,
KeyToBool: true,
KeyToDateTime: 2016-10-09,
KeyToArray: [ "String", 1, 1.2, true, 2016-10-09, ],
KeyToMap:
{
KeyToString: "String inside nested map",
},
},The filename extension for SKON files is .skon.
In SKON, a file is implicitly considered to be a map, that means that every value in a SKON file must be a key-value pair.
To store the data in the previous example as a valid SKON file you could either wrap everything in a surrounding map.
KeyToMap: { ... }
Or preferably write every element as a key-value pair without the surrounding map.
~Version: 1~
~DocumentVersion: ""~
KeyToString: "String value",
KeyToInt: 1,
KeyToFloat: 1.2,
KeyToBool: true,
KeyToDateTime: 2016-10-09,
KeyToArray: [ "String", 1, 1.2, true, 2016-10-09, ],
KeyToMap:
{
KeyToString: "String inside nested map",
},